home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Arsenal Files 8
/
The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO
/
prg_casm
/
pcl4c60.zip
/
PCL4CUSR.DOC
< prev
next >
Wrap
Text File
|
1996-10-24
|
90KB
|
2,102 lines
Personal Communications Library
For the C Language
(PCL4C)
USERS MANUAL
Version 6.0
October 21, 1996
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1995
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 205-881-4630
FAX : 205|880|0925
BBS : 205-880-9748
email : info@marshallsoft.com
Anon FTP : ftp.marshallsoft.com /marshallsoft
web : www.marshallsoft.com
_______
____|__ | (R)
--+ | +-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
--+--+ | +---------------------
|___|___| MEMBER
PCL4C Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 ASP Ombudsman...........................................4
1.3 A Typical Application...................................5
1.4 Installation............................................6
2.0 Library Organization........................................7
2.1 Configuration...........................................7
2.2 Initialization & Termination............................7
2.3 Modem Control & Status..................................8
2.4 Serial I/O..............................................8
2.5 Error Detection.........................................9
2.6 General Support.........................................9
3.0 Library Overview...........................................10
3.1 Memory Models..........................................10
3.2 16-bit Protected Mode..................................11
3.3 32-bit Protected Mode..................................12
3.4 Compilers Supported....................................13
3.5 Using the Library......................................13
3.6 Application Notes......................................14
3.7 Compiling & Linking....................................15
4.0 Talking to Your Modem......................................16
4.1 Modem Standards........................................16
4.2 Flow Control...........................................17
4.3 MODEM_IO functions.....................................17
4.4 Modem Initialization...................................18
5.0 Problems...................................................19
6.0 Serial Communications......................................20
6.1 Communications Basics..................................20
6.2 Standard Port Addresses................................21
6.3 Running 3 or 4 Ports Concurrently......................22
6.4 Using Multiport Cards..................................23
6.5 Transmitter Interrupts.................................24
6.6 RS232 Signals..........................................25
6.7 National INS8250, INS16450, and INS16550 UARTs.........26
6.8 Register Summary.......................................27
7.0 Example Programs...........................................29
8.0 Legal Issues...............................................30
8.1 Registration...........................................30
8.2 License................................................30
8.3 Warranty...............................................31
9.0 Summary....................................................32
9.1 Revision History.......................................32
9.2 Function Summary.......................................34
9.3 Further Reading........................................34
10.0 Other MarshallSoft Computing products for C................35
10.1 The Personal Protocol Library for C...................35
10.2 The EMS Expanded Memory Library for C.................35
10.3 Other Products........................................35
PCL4C Users Manual Page 2
1.0 Introduction
The Personal Communications Library for the C Language (PCL4C) is an
asynchronous communications library designed for experienced software
developers programming in C/C++. Six compilers are supported:
Microsoft C, Quick C, Borland C, Turbo C, Watcom C, and MIX Power C.
An IBM PC/XT/AT or compatible is required. The PCL features:
o Supports 16-bit & 32-bit PROTECTED MODE.
o SMALL, COMPACT, MEDIUM, LARGE, & FLAT memory models.
o 38 communications and support functions.
o Supports the high performance 16550 UART.
o Supports the PC/4 and PC/8 DigiBoard.
o Supports the BOCA BB1004, BB1008, and BB2016 boards.
o Supports hardware (RTS/CTS) flow control.
o Interrupt driven transmitter & receiver.
o Supports 300 baud to 115,200 baud.
o Use IRQ2 through IRQ15 with any UART address.
o Supports COM1 thru COM4 (COM20 in registered version).
o Adjustable receive queues from 8 bytes to 32 KB.
o Control-BREAK error exit.
o 18 communications error conditions trapped.
o Allows 4 ports to run concurrently (more with multiport).
o Complete modem control & status.
o Written in assembly language for small size & high speed.
o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
YMODEM, & YMODEM-G.
Why should you buy PCL4C ? Several good reasons are:
COMPLETE - PCL4C is complete since it provides absolute control of
the serial ports (including the 16550 UART).
COMPACT - PCL4C is very compact at less than 10 KB. Your
application doesn't carry a lot of excess code.
FAST - PCL4C is fast since it will run at 38400 baud on even
slow 8088 PCs (4.77 MHZ) and at 115200 baud on most
everything else.
SUPPORT - If you get stuck, you talk to the programmer that wrote
the code, not a person hired to answer the phone.
BBS - A BBS is available (to 14400 baud, N81) in order to
provide immediate support as necessary.
NEWSLETTER - We publish a quarterly newsletter "Comm Talk", which
discusses serial communications problems and solutions.
PRICE - You get PCL4C for a very reasonable price!
UPGRADES - Once you buy PCL4C, you can always update to the most
recent version very inexpensively ($25 plus shipping).
PCL4C Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using
PCL4C! We depend on our customers to let us know what they need in a
communications library. This means we are committed to providing the
best communications library that we can. If you have any suggestions
or comments, please let us know!
We provide customer support for registered customers by voice, BBS,
email, and US mail.
If you are having a problem using PCL4C, call us at 205-881-4630
between 1:30 PM and 9:30 PM (CST) Monday through Friday. You can also
call at other times and leave a message, and call back later for a
reply. We cannot return phone calls.
However, we can only answer questions with respect to using the
PCL4C library. We cannot help you program your application, but we'll
be glad to discuss it with you.
You may also call our User Support BBS (2400 to 14400 baud, no
parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a message
(address it to the SYSOP). We will usually have a reply ready for
you within 24 hours.
The BBS is available 24 hours per day. All files are in standard ZIP
format. The BBS will contain the latest shareware version of all
MarshallSoft Computing products as well as related files such as:
BUGS.ZIP - Bug report.
PRODUCTS.ZIP - List of all shareware products.
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published
quarterly. It discusses various communications problems and
solutions using PCL4C as well as related information.
The latest copy of our newsletter can be found on our support BBS,
anonymous FTP site, or on our Web site.
BBS : 205-880-9748 (file area "Newsletters")
Anon FTP : ftp.marshallsoft.com (directory /marshallsoft)
Web site : www.marshallsoft.com
1.2 ASP Ombudsman
MarshallSoft Computing, Inc. is a member of the Association of
Shareware Professionals (ASP). ASP wants to make sure that the
shareware principle works for you. If you are unable to resolve a
shareware-related problem with an ASP member by contacting the member
directly, ASP may be able to help. The ASP Ombudsman can help you
resolve a dispute or problem with an ASP member, but does not provide
technical support for members' products. Please write to the ASP
Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax
616-788-2765, or send a CompuServe message via CompuServe Mail to
ASP Ombudsman 70007,3536.
PCL4C Users Manual Page 4
1.3 A Typical Application
In general, there are two classes of applications that use a
communications library like PCL4C - those that use a modem to connect
to the outside world and those that connect directly to a peripheral
device. In either case, a typical (real mode) application program
using PCL4C might look like the following code outline:
+---------------------------------------------------+
| #include "pcl4c.h" |
| |
| void main(void) |
| { |
| ... |
| /* initialize serial comm system */ |
| SioRxBuf(Port,AllocSeg(1024),Size1024); |
| SioTxBuf(Port,AllocSeg(128),Size128); |
| SioParms(Port,NoParity,OneStopBit,WordLength8); |
| SioReset(Port,Baud2400); |
| |
| ...application code... |
| |
| /* terminate serial comm system */ |
| SioDone(Port); |
| } |
+---------------------------------------------------+
In the above example, SioRxBuf is called to set up the a 1024 byte
receive buffer; SioTxBuf is called to set up a 128 byte transmit
buffer; SioParms is called to set up the parity, stop bit count, and
word length; SioReset is called to set the baud rate to 2400 and
reset the UART (Univeral Asynchronous Receiver / Transmitter).
The function AllocSeg allocates a buffer of specified size on the
far heap and returns the segment SEG such that SEG:0 points to the
buffer. The function AllocSeg is part of the example code and can be
found in the file ALLOCSEG.C.
Before leaving your application, SioDone is called to restore the
prior state of the serial communications system.
If you are using a modem, you also need to be concerned about
initializing your modem correctly and handling any required flow
control. Refer to the "Talking to Your Modem" chapter for detailed
information.
The communication library has been pre-assembled to library files:
PCL4C_S.LIB : Small memory model.
PCL4C_C.LIB : Compact memory model.
PCL4C_M.LIB : Medium memory model.
PCL4C_L.LIB : Large memory model.
PCL4C_P.LIB : 16-bit Protected mode [Large model].
PCL4C32.OBJ : 32-bit Protected Mode [Flat model].
PCL4C_S.MIX : MIX PowerC small memory model.
PCL4C_M.MIX : MIX PowerC medium memory model.
PCL4C_L.MIX : MIX PowerC large memory model.
PCL4C Users Manual Page 5
1.4 Installation
(1) Before installation of PCL4C, your C compiler should already be
installed on your system and tested. If you are not familiar with
makefiles, refer to your compiler manual. If you are using the
interactive environment for Quick C or Turbo C, be sure to compile
with the memory model corresponding to the PCL4C library used, and
include the correct library in the project file. Examine the file
"FILES.LST" for a list of all the distribution files.
(2) Make a backup copy of your distribution disk. Put your original
distribution disk in a safe place.
(3) Create a work directory on your work disk (normally your
harddisk). For example, to create a work directory named PCL4C, we
first log onto the work disk and then type:
MKDIR PCL4C
(4) Copy all the files from your backup copy of the distribution
disk to your work directory. For example, to copy from the A: drive
to your work directory, we type:
CD PCL4C
COPY A:*.*
(5) [OPTIONAL] Delete the makefiles that you won't need. For
example, if you use the Microsoft C compiler, then you want to keep
all makefiles ending *._M_ but can delete those for Turbo C (*._T_),
Quick C (*._Q_), and MIX Power C (*.PRJ). You may also delete any
libraries that you won't need.
(6) Compile SIMPLE.C and link with the appropriate PCL4C library
(PCL4C_S.LIB for all but Power C which must use PCL4C_S.MIX).
Makefiles (or project files) are provided for each of the supported
compilers.
a) Microsoft C/C++: MAKE SIMPLE._M_
b) Microsoft QuickC: MAKE SIMPLE._Q_
c) Borland C/C++: MAKER -fSIMPLE._B_
(32-bit) MAKER -fSIMPLE32._B_
d) Turbo C/C++: MAKE -fSIMPLE._T_
e) MIX Power C: PC/E SIMPLE.PRJ
f) WATCOM C/C++: WMAKE -f SIMPLE._W_
(32-bit) WMAKE -f SIMPLE32._W_
SIMPLE.C [or SIMPLE32.C] should compile without any problems as all
example code has been tested with each of the supported compilers.
(7) The recommended way to test SIMPLE is to run it on two computers
connected by a null modem cable. Whatever is typed on one computer
should be displayed on the other.
SIMPLE can also be tested by connecting your port to a modem.
Transmitting a "AT" to the modem should result in an "OK" being
received.
PCL4C Users Manual Page 6
2.0 Library Organization
The PCL4C library is organized into six categories of functions.
Refer to the PCL Reference Manual (PCL4C.REF) for details on
individual functions.
2.1 Configuration
There are three functions in the configuration category. SioPorts
sets the number of PC and DigiBoard (or BOCA board) ports. SioUART is
used to change the UART base address for a communications port to a
non-standard address, while SioIRQ is used to assign a nonstandard
IRQ line to a port. (See chapter 6, Serial Communications for more
details on standard UART addresses and IRQ lines).
The configuration functions SioPorts, SioUART and SioIRQ must be
called before calling any other library functions. Be very careful
in using these functions. Remember that your serial hardware must
support the UART and IRQ that you specify. Always test any new
configuration immediately.
SioPorts - Sets number of PC and DigiBoard (or BOCA board) ports.
SioUART | Sets the UART base address.
SioIRQ - Assigns an IRQ line to a port.
THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per
IRQ (except for the DigiBoard and BOCA board).
2.2 Initialization & Termination
There are eight functions in the initialization and termination
category. Together, SioParms, SioFIFO, SioRxBuf, SioTxBuf, and
SioReset initialize your serial communications system. Your
application must call SioRxBuf and SioTxBuf before calling SioReset,
and SioReset must be called before any serial I/O processing can be
done.
After initialization, SioParms and SioBaud can be called to change
the communications parameters without resetting the serial port.
SioFlow can be called to enable hardware flow control. SioFIFO can
be called to set the interrupt level for the 16550 FIFO.
Before exiting from your application, SioDone must be called.
Failure to call SioDone can crash your system later.
SioRxBuf : Sets up receive buffer.
SioTxBuf : Sets up transmitter buffer.
SioFIFO : Sets the interrupt level for the INS16550.
SioParms : Sets parity, stop bits, and word length.
SioReset : Initialize a serial port for processing.
SioDone : Terminates further serial processing.
SioBaud : Sets the baud rate of the selected port.
SioFlow : Enables / disables hardware flow control.
PCL4C Users Manual Page 7
2.3 Modem Control & Status
There are nine functions in the modem control and status category
which provide your application with complete control over the status
and control bits of your modem.
There are two modem control bits, "Data Terminal Ready" (DTR) and
"Request To Send" (RTS). These bits can be read, set, or cleared by
SioDTR and SioRTS.
There are four modem status bits, "Data Set Ready" (DSR), "Clear To
Send" (CTS), "Ring Indicator" (RI), and "Data Carrier Detect" (DCD).
SioModem can read any of the modem status bits. SioDSR, SioCTS,
SioRI, and SioDCD can only read their respective modem status bit.
SioGetDiv reads the baud rate divisor register so the baud rate can
be determined.
Refer to the chapter entitled "RS232 Signals" for a discussion of
each of the control and status bits.
SioDTR : Set, clear, or read the Data Terminal Ready (DTR) bit.
SioRTS : Sets, clears, or reads the Request to Send (RTS) line.
SioModem : Reads the modem status register.
SioDSR : Reads the Data Set Ready (DSR) modem status bit.
SioCTS : Reads the Clear to Send (CTS) modem status bit
SioDCD : Reads the Data Carrier Detect (DCD) modem status bit.
SioRI : Reads the Ring Indicator (RI) modem status bit.
SioRead : Reads the contents of the 7 UART registers.
SioGetDiv : Reads the baud rate divisor registers.
2.4 Serial I/O
There are eleven library functions in the serial I/O category.
Together, these functions give the programmer complete control over
serial I/O. Higher level functions such as protocols and smart modem
communications can be completely implemented in terms of these
functions. Refer to the example code.
SioGetc, SioGets, SioPutc, and SioPuts perform all the actual serial
I/O. SioUnGetc "ungets" the last serial byte read. SioRxClear clears
the receive queue while SioTxClear clears the transmit queue.
SioTxFlush flushes the transmit queue. SioLine can be used to test
for UART errors. SioRxQue returns the number of bytes in the receive
queue while SioTxQue returns the number of bytes in the transmit
queue.
SioGetc : Reads the next character from the serial line.
SioGets : Reads a buffer of characters from the serial line.
SioLine : Reads the line status register.
SioPutc : Transmit a character over a serial line.
SioPuts : Transmit a buffer of characters over a serial line.
SioRxClear : Clears the RX buffer.
SioRxQue : Returns the number of characters in the RX queue.
SioTxClear : Clears the TX buffer.
SioTxFlush : Flushes the TX buffer by restarting TX interrupts.
SioTxQue : Returns the number of characters in the TX queue.
SioUnGetc : "Un:gets" (puts back) a specified character.
PCL4C Users Manual Page 8
2.5 Error Detection
There are four functions in the error detection category. They are
concerned with detecting or reporting communications errors. Use of
these functions can make your application significantly more robust.
SioBrkKey can be used as an "emergency" exit from your application.
SioBrkSig can read or modify the UART break bit. This is useful for
signalling the remote system that a fatal condition has occurred.
SioLoopBack can be used to test the integrity of your UART. SioError
displays a error message corresponding to an error code returned from
a PCL4C function (every PCL4C function returns a code).
SioBrkKey : Returns !0 if CTL-BREAK was pressed [16-bit lib only].
SioBrkSig : Asserts, cancels, or detects the RS232 BREAK signal.
SioError : Displays error in text [32-bit lib uses SioErr32.C].
SioLoopBack : Performs a UART loopback test. [16-bit lib only].
2.6 General Support
There are three functions in the general support category. They are
as follows:
SioInfo : Returns library information such as version number.
SioStats : Return port specific statistics [32-bit only].
SioDelay : Delays one or more tics (18.2 tics per second).
SioTimer : Returns the number of system clock tics.
PCL4C Users Manual Page 9
3.0 Library Organization
3.1 Memory Models
Because of the segmented architecture of the INTEL CPU, there are
four real mode memory organizations possible for computer programs.
These are named the SMALL, COMPACT, MEDIUM, and LARGE memory models,
which correspond to the four combinations of "near" and "far"
addresses for code and data.
Each (real mode) executable is composed of one or more segments,
where each segment can occupy from one byte to 64 KB of memory. A
"near" address is a 16 bit offset in a segment, whereas a "far"
address consists of both a 16 bit segment value and a 16 bit offset.
In the small memory model, code and data each occupy one segment.
Thus, near addresses are allocated for both code and data.
In the compact memory model, code occupies one segment while data
may occupy multiple segments. Near addresses are allocated for code
but far addresses are allocated for data.
In the medium memory model, data occupies one segment while code may
occupy multiple segments. Near addresses are allocated for data but
far addresses are allocated for code.
In the large memory model, data and code each occupy multiple
segments. Far addesses are allocated for both code and data. Thus,
both code and data can use as many segments as required.
Refer to your compiler manual for a discussion of the memory models
supported by your compiler.
PCL4C is organized as four separate libraries (PCL4C_S.LIB,
PCL4C_C.LIB, PCL4C_M.LIB and PCL4C_L.LIB) corresponding to the four
standard memory models. For the MIX Power C compiler, the small,
medium, and large models are provided. Lastly, there is the 16-bit
and 32-bit protected mode model which is linked into protected mode
applications.
MODEL CODE DATA Library
Small Near Near PCL4C_S.LIB & PCL4C_S.MIX
Compact Near Far PCL4C_C.LIB
Medium Far Near PCL4C_M.LIB & PCL4C_M.MIX
Large Far Far PCL4C_L.LIB & PCL4C_L.MIX
Protected Far Far PCL4C_P.LIB [16-bit PM only].
Flat Near Near PCL4C32.OBJ [32-bit PM only].
However, one can always use the large memory model library
PCL4C_L.LIB with any memory model application code by explicitly
declaring the PCL4C procedures to be FAR (by prefixing "far" before
the name of each function in the PCL4C.H file) and declaring your
receive buffer to be FAR. If you are compiling with the HUGE memory
mode (real mode), link with PCL4C_L.LIB.
PCL4C Users Manual Page 10
3.2 16-Bit Protected Mode
16-Bit Protected Mode programming takes advantage of the segmented
architecture of 286 and up Intel processors. In contrast to normal
real mode programming which limits programs to an address space of 1
MB (1024 KB), 16-bit protected mode allows up to 16 MB. Protected
mode also offers some measure of protection of one program from
another.
A program that can execute in protected mode under DOS requires three
modules:
(1) A DPMI (DOS Protected Mode Interface) server loaded in memory.
Execute the real mode program DPMI.EXE to determine if a DPMI server
is loaded.
(2) A protected mode runtime C library linked to your program.
(3) A 16-bit DOS extender which provides protected mode equivalents
for:
a) A subset of DOS interrupt 21H calls.
b) A subset of BIOS calls.
The Personal Communications Library (PCL4C_P.LIB) supports 16-bit
protected mode. The application program must be compiled with a C/C++
compiler that supports protected mode. The Borland PowerPack for DOS
provides all the required modules, although the library can be used
by any DOS extender that provides the three required components as
outlined above.
Examine the example program PMSIMPL.C, which is a (16-bit) protected
mode version of the normal DOS based SIMPLE.C. Compare it to
SIMPLE.C to see the differences necessary to run in protected mode.
In particular, note the manner in which memory is allocated for use
in PCL. The transmit and receive buffers must be allocated in
conventional DOS memory (the first 1MB) since serial interrupts can
occur during both protected mode and real mode.
Also notice that memory should be free after calling SioDone but
before exiting:
Examine the makefile (PMSIMPLE._B_) used to compile PMSIMPLE.C using
the Borland compiler and Borland's PowerPack for DOS.
The program SELFTEST.C can also be compiled for protected mode by
using the makefile PM_SELF._B_.
For more information on protected mode, refer to your DOS extender
such as the Borland Power Pack.
PCL4C Users Manual Page 11
3.3 32-Bit Protected Mode
32-bit Protected Mode programming takes advantage of the 32-bit flat
memory architecture of 386 and up Intel processors. In contrast to
real mode programming which limits programs to an address space of
one MB, a 32-bit Protected Mode program can address four GB.
The 32-bit flat memory model uses 48-bit addesses: a 16-bit selector
plus a 32-bit offset. The selectors are not usually modified by the
application code, although the DOS extender and PCL4C32 do manipulate
them.
32-bit Protected Mode programming requires a 386 (or higher) CPU, a
C/C++ compiler that can generate 32-bit code, and a 32-bit DOS
extender which supports the DPMI standard. PCL4C32 has been tested
with two 32-bit compilers: Borland 4.5 (using the Borland Power Pack
extender 32RTM) and WATCOM 10.5 & 10.6 (using the DOS4GW extender
which comes with the WATCOM compiler). Other 32-bit DOS extenders may
also work provided that DPMI services are available.
If you are shopping for a 32-bit compiler, we recommend WATCOM. Their
DOS extender (DOS4GW) is very stable and WATCOM even has technical
support (no credit card or 900 number required!).
You must have a DPMI server loaded in order to use the 32-bit PCL4C
library. There are several options. If you are using Windows 3.X or
Windows 95, simply drop into a DOS box since Windows itself requires
DPMI. A better solution is to configure your memory manager (386Max,
etc.) to provide DPMI support, typically by disabling EMS memory.
Refer to your memory manager's manual.
Execute the real mode program DPMI.EXE to determine if a DPMI server
is loaded.
Examine the two 32-bit example programs SIMPLE32.C and SELF32.C. The
corresponding makefiles are SIMPLE32._B_, SIMPLE32._W_, SELF32._B_,
and SELF32._W_. Note that a 0 can be passed as the second argument
to SioRxBuf and SioTxBuf which will cause PCL4C32 to allocate all
required memory itself.
The shareware version of PCL4C is limited to 4 ports and can not
execute for more than 5 minutes at any one time without having to
restart the application. The registered version supports up to 20
ports and has no shareware reminder screen or any time limits. The
assembly language source code for the PCL4C32 library is not
provided.
PCL4C Users Manual Page 12
3.4 Compilers Supported
At this time, six C compilers are supported by PCL4C.
(1) Microsoft C Compiler.
(2) Quick C Compiler.
(3) Turbo C Compiler.
(4) Borland C Compiler [also 32-bit with Power Pack].
(5) MIX Power C Compiler
(6) Watcom C compiler [also 32-bit].
The Microsoft C Compiler supports all memory models. Just be careful
to link with the PCL4C library that corresponds to the memory model
used. Recall that the small memory model is the default. Examine
the (small model) makefiles *._M_ for the Microsoft compiler.
The Microsoft Quick C Compiler supports all memory models, but be
careful to link with the PCL4C library that corresponds with the
memory model used. Recall that the small memory model is the default
for the command line compiler (QCL) while the medium memory model is
the default for the interactive compiler environment. Examine the
(small model) makefiles *._Q_ for the Microsoft Quick C compiler.
The Borland and Turbo C Compilers also support all memory models. Be
sure to link with the correct PCL4C library corresponding to the
memory model used. Examine the (small model) makefiles *._T_ for the
Turbo C compiler and *._B_ for the Borland compiler.
The MIX Power C Compiler supports the small, medium, and large
memory models. However, older versions of Power C only support the
small model. Examine the (small model) project batch files *.PRJ for
the Power C Compiler.
Other compilers may also work with one or more of the PCL4C libraries
but have not been tested. Give us a call if you have any difficulty.
3.5 Using the Library
Please examine the PCL4C.H file (PCL4C32.H for 32-bit). Note that
COM1 is defined as port zero, not port one. The user must assume the
responsibilty for passing the correct information when calling PCL4C
functions.
If there are any conflicts between PCL4C definitions and those in
other libraries, the PCL4C definitions can be changed in the PCL4C.H
file and any file that uses the definition. There is no change
necessary for the library code itself.
The PCL4C libraries (16 and 32 bit) contain no references to any
runtime libraries. Only BIOS and MSDOS functions are called.
PCL4C Users Manual Page 13
3.6 Application Notes
3.6.1 Terminal Programs
The "terminal program" is the most common class of communications
program. It is used to call up a BBS or on-line service such as
CompuServe, America On-Line, etc. Refer to the programs SIMPLE and
LOGIN in section 7 for examples of simple terminal programs.
A more sophisticated terminal program featuring ASCII, XMODEM,
YMODEM, and ZMODEM protocol file transfers can be found in our sister
product -- The Personal Protocol Libray (PPL4C). Source code is
included in the shareware distribution for everything except ZMODEM
and the script intepreter.
3.6.2 Door Programs
In order to write a door program which "takes over" a serial port
without resetting the port or changing the baud rate, call SioReset
with NORESET as the second argument rather than the baud rate. Call
SioGetDiv to get the baud rate divisor if the baud rate must be
determined. Be sure to call SioDone before returning to the invoking
program. Refer to the SPAWN.C and DOOR.C example programs. Also be
sure to free any memory that you may have allocated in your door
program before exiting.
3.6.3 BBS Programs
If you are designing a BBS program (also known as HOST programs),
consider using 16550 UARTS. You should also choose a multiport card
such as the DigiBoard or BOCA board if you wish to run more than 4
ports simultaneously.
If you are using an error correcting modem, then you should be sure
to set flow control and fix your baud rate at the highest possible
transfer rates. For 14,400 modems, this means 19200 or 38400. You
may need a 16550 UART in order to run at the higher speed.
If you are using an older multi-speed modem (say 1200, 2400, 4800,
9600) that doesn't use flow control, you should change your baud rate
to match the CONNECT message baud rate.
3.6.4 Communicating with Devices
If you will be communicating with a serial device (motor control,
digitizing tablet, etc.) be sure to (1) not enable flow control
include unless you are certain that flow control is used by the
serial device, (2) include a short delay after sending each character
to the serial device (start with 1/4 second), and (3) set DTR and RTS
since many devices require DTR to be set before they will respond.
As a first step, try to communicate with the serial device using a
terminal emulator such as SIMPLE.
PCL4C Users Manual Page 14
3.7 Compiling and Linking
Registered users may wish to assemble (16-bit) PCL4C.ASM. Use the
/MX switch in order to disable automatic conversion from lower case
to upper case. If the /MX switch is not used, then all PCL4C
function references in C code must be in upper case.
Model Command
Small MASM PCL4C /DSMALL_MODEL /MX;
Compact MASM PCL4C /DCOMPACT_MODEL /MX;
Medium MASM PCL4C /DMEDIUM_MODEL /MX;
Large MASM PCL4C /DLARGE_MODEL /MX;
To disable transmitter interrupts, add "/DNO_TBE" to each MASM
command line above.
For example, to make the (small) model PCL4C.OBJ into a library file:
DEL PCL4C_S.LIB
LIB PCL4C_S.LIB+PCL4C,PCL4C.MAP;
If you are using the MIX Power C Compiler, create the MIX object
file (you will need version 1.3 of MIX which has the /_ switch):
MIX /_ PCL4C_S
Similarly with the other memory model libaries. See the batch files
MAKE_S.BAT, MAKE_C.BAT, MAKE_M.BAT, and MAKE_L.BAT. Similiarly for
MAKE_ST.BAT, MAKE_CT.BAT, MAKE_MT.BAT, and MAKE_LT.BAT.
To compile and link (small model) using:
Microsoft C: NMAKE SIMPLE._M_
Quick C: QCL /AS SIMPLE.C /LINK PCL4C_S.LIB
Borland C: MAKER -fSIMPLE._B_
MAKE -fSIMPLE32._B_ [32-bit]
Turbo: MAKE -fSIMPLE._T_
MIX Power C: PC/E /ms SIMPLE.C PCL4C_S.MIX
WATCOM C: WMAKE -f SIMPLE._W_
WMAKE -f SIMPLE32._W_ [32-bit]
Makefiles or project files are provided for all example code. Borland
makefiles end with the extension '._B_', Turbo C makefiles with
'._T_', Microsoft C makefiles end with '._M_', Microsoft Quick C
makefiles files end with '._Q_', WATCOM makefiles end with '._W_',
and Power C project batch files end with '.PRJ'.
The PCL4C libraries may also be used with integrated development
environments. Place all required files along with the library
corresponding to the memory model being used into the project file.
Be sure to select the appropriate memory model, and turn off all case
sensitivity.
PCL4C Users Manual Page 15
4.0 Talking to Your Modem
A modem is used to extend the distance over which you may
communicate. Without a modem, your RS232 cable is limited to a
maximum of approximately 50 feet. But with a modem, you can
communicate literally around the world.
Also refer to Section 4.3 for details on MODEM_IO functions. These
functions faciliate communications with modems.
4.1 Modem Standards
Two modems can communicate over a telephone line only if they are
both using the same signaling frequencies and modulation, which are
determined by the the modem standards used. Modem standards can be
divided into three sets: (1) speed, (2) data compression used, and
(3) error control.
The Bell standards (103 & 212A) are those of AT&T. The CCITT (The
International Consultative Committee for Telephone and Telegraph)
standards are designated as "V. ".
Speed
Bell 103 : 300 baud
Bell 212A : 1200 baud
V.21 : 300 baud
V.22bis : 1200 & 2400 baud
V.32 : 4800 & 9600 baud
V.32bis : 4800, 7200, 9600, 12000, and 14400 baud
V.34 : through 28800 baud
Data Compression
MNP 5 : Microcom Networking Protocol (proprietary).
V.42bis : International data compression standard.
Error Control
MNP 2,3,4 : Three level error correction (public domain).
V.42 : International error correction standard.
Most of the newer high speed modems use several of the above
standards. However, not all combinations of modem makes communicate
easily with each other, especially at high speeds (9600 and up).
PCL4C Users Manual Page 16
4.2 Flow Control
With modems using data compression, the modem to modem connection
will run at various speeds depending on the quality of the line. The
computer to modem connection will be at a fixed baud rate. Therefore,
a protocol (flow control) is necessary to synchronize the data flow
between a modem and the computer to which it is connected.
Two flow control protocols are used by modems which require flow
control. Software flow control is called "XON/XOFF" and hardware flow
control is called "RTS/CTS".
4.2.1 Software Flow Control (XON/XOFF)
In XON/XOFF (software) flow control, the computer suspends
transmitting data if it receives a XOFF character (13 hex) from the
modem, and continues transmitting when it receives a XON character
(11 hex). Similiarly, the computer can signal the modem not to send
any more data by transmitting a XOFF to it, and can tell the modem to
continue transmission be sending a XON.
Software flow control cannot be used to transfer binary data since
binary data may have hex 11 or hex 13 bytes embedded in it. The ASCII
protocol typically uses XON/XOFF to control display flow while the
modem may be using RTS/CTS. Refer to the module XONOFF.C.
4.2.2 Hardware Flow Control (RTS/CTS)
In RTS/CTS (hardware) flow control, the RTS line is used by the
computer to signal the modem , while the CTS line is used by the
modem to signal the computer. The RTS line is set OFF by the
computer to tell the modem to suspend transmission, and set to ON to
tell the modem to continue transmission. The CTS line is set to OFF
by the modem to tell the computer to stop transmitting, and set to ON
to tell the computer to continue transmitting.
Given the choice, always choose hardware flow control over software
flow control so that all data transmission is transparent. If
hardware flow control is not the default (which it almost always is),
you should modify your modem initialization string to turn hardware
flow control on.
Hardware flow control is internal to the PCL4C library and is
selected by the SioFlow function.
4.3 MODEM_IO Functions
The file MODEM_IO.C has several functions that ease communicating
with your modem. Look in LOGIN.C for examples of use.
ModemSendTo : Sends string (including control chars) to the modem.
ModemWaitFor : Waits for a string from the modem, passing all else through.
ModemQuiet : Waits for continuous quiet of specified duration.
ModemHangup : Hangs up the modem.
ModemCmdState : Goes into the modem's command state.
ModemEcho : Echos all serial incoming bytes to the display.
PCL4C Users Manual Page 17
4.4 Modem Initialization
If your application uses a modem (as opposed to using a null modem
cable), then you should always send an initialization string to your
modem if it is a programmable modem such as those made by Hayes.
Communication programs such as PROCOMM and TELIX always send such a
string automatically as soon as they start up.
The particular initialization string depends on the make of your
modem. Virtually all modems implement the basic Hayes AT command set,
and add their own "extended" AT commands. These extended AT commands
vary among modem manufacturers.
For AT command set modems the following string (followed by a
carriage return) may work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Modem User's Guide for a full discussion of these
commands. A brief description is as follows:
AT : Modem attention command.
E1 : Modem will echo what you send to it.
S7=60 : Wait 60 seconds for carrier and/or dial tone.
S11=60 : Use 60 milliseconds for tone dialing duration & spacing.
V1 : Display result code as words (not numbers).
X1 : Use the extended result message (CONNECT XXXX) set.
Q0 : Modem returns result codes.
S0=0 : Do not answer RING.
If your application will answer incoming calls, then set the S0
register to the ring on which to automatically answer.
Alternatively, use the ATA command to explicitly answer the modem
after detecting the RING.
If you send the above codes by using SioPutc (as opposed to typing
them from the keyboard), then follow these guidelines:
(1) Send an initial carriage return before the initialization string.
(2) Pause at least two tics (18 tics to the second) after each
character sent as your modem needs the time to perform its own
internal processing. Pause a little longer if your modem is not
accepting your initialization string.
(3) Pause two seconds after sending any initialization command such
as ATZ or AT&F since your modem must do quite a bit of processing.
If you experience any problems in initializing your modem, you
should first reset it to factory settings by sending:
AT&F
Your modem may require more initialization than presented above.
Refer to your modem manual for details. If you have a communications
program such as ProComm or Telix that is known to initialize your
modem correctly, then use the same initialization string.
PCL4C Users Manual Page 18
5.0 Problems
Before developing your application, you should run the example
programs. They should all execute correctly.
If you have two ports on your computer, connect them together with a
null modem cable and run SELFTEST.C. If SELFTEST does not execute
properly then there is something wrong with either (1) your serial
port hardware, (2) your null modem cable, or (3) you selected ports
that are not connected by the null modem cable.
Another easy test is to connect the serial port to a modem, and use
SIMPLE to send a "AT" to the modem, which should respond with a
"OK". If you cannot get your application to run properly, first
compile and run the terminal emulator program SIMPLE provided on your
distribution disk.
If your application does not run but the example programs run
correctly, then you have most likely made a programming mistake in
your application. MarshallSoft Computing cannot debug your
application, especially over the telephone! However, consider each
of the following when searching for an error in your application.
1. Have you included the file PCL4C.H in your application ?
2. Did you link with the correct PCL4C library ? This is the most
probable cause if your application 'hangs' as soon as it starts and
you must reboot. The function SioInfo('M') returns the model ID under
which the library was assembled.
3. Is your receive buffer large enough ? If you are using 1K data
blocks in YMODEM, then your receive buffer should be at least 1K (2K
if baud rates above 19200 are to be used).
4. Have you selected too high a baud rate (if you are using a slow
PC) ? If only one COM port is being run, you should be able to run
at 38400 baud on 8088 machines and 115200 on most 286s and above.
5. Are you attempting to run another application in the background ?
Try running without any other programs running in the background.
6. If you are running two COM ports simultaneously, are you using
separate receive and transmit buffers ? (you should).
7. Did SioReset return a zero value ? If not, then you must call
SioReset again. See SIMPLE.C for an example.
8. Did you send the proper initialization string to your modem ?
Did you set DTR and RTS ? (you should).
9. Do you have more than one COM1 port, etc. For example, if you
have a COM1 port on your motherboard, you cannot add another COM1
port or modem board that uses COM1 without first disabling the COM1
on the motherboard.
10. Are you passing the proper segment of the receive (and
transmit) buffer? See SIMPLE.C for an example.
PCL4C Users Manual Page 19
6.0 Serial Communications
6.1 Communications Basics
The heart of serial communications is the UART (Universal
Asynchronous Receiver Transmitter). The IBM PC/XT/AT and compatibles
use the INS8250, INS16450, or the INS16550 UART. The purpose of the
UART is:
(1) To convert bytes from the CPU (Central Processing Unit), into a
serial format by adding the necessary start, stop, and parity bits to
each byte before transmission, and to then transmit each bit at the
correct baud rate.
(2) To convert the incoming stream (at a specified baud rate) of
serial bits into bytes by removing the start, stop, and parity bits
before being made available to the CPU.
The UART is part of the serial interface circuitry which allows the
CPU to send and receive signals over the RS232 lines. This can be
diagrammed as follows:
Serial Interface
+-------------------+
| |
+-----+ Data Bus | +------+ | RS232 Signals
| CPU +------------+ | UART | +----------------*
+-----+ | +------+ |
| |
+-------------------+
The INS8250/16450/16550 UART is capable of operating in one of two
modes, "polled" and "interrupt driven". The serial communications
functions in the BIOS uses the polled method. In this approach, the
CPU is typically in a loop asking the UART over and over again if it
has a byte ready. If it does, the polling code returns the byte.
But, if the next byte comes in before the polling code is executing
again, then that byte is lost.
In the interrupt driven approach, when a byte is received by the
UART, an interrupt is generated and the "Interrupt Service Routine"
(ISR) is executed immediately, suspending temporarily whatever else
is executing. The ISR then moves the byte to the receive buffer so
that your application program can later read it.
When a byte is to be transmitted, it is moved to the transmit queue
and transmitter interrupts are "kickstarted", which causes an
interrupt to be generated each time the transmitter buffer becomes
empty. The ISR is invoked, which removes the byte from the
transmitter queue and writes it to the UART transmit buffer.
Refer to section 6.5 "Transmitter Interrupts", section 6.6 "RS232
Signals", and section 6.7 "National INS8250, INS16450 and INS16550
UARTs" for further information on these topics.
PCL4C Users Manual Page 20
6.2 Standard Port Addresses
There are a few things to know about how serial communications ports
are used by IBM PC/XT/AT and compatible computers. The standard IBM
PC/XT/AT configuration values are as follows:
Port Reg. IRQ Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
(Refer to your DigiBoard manual for DigiBoard addresses, or your
BOCA board manual for BOCA port addresses).
PCL4C assumes the above values. If necessary, the UART base address
can be changed by SioUART, and IRQ lines can be re-assigned by
SioIRQ. Remember that each port to be used concurrently must have a
unique IRQ line. Refer to the PCL4C Reference Manual for specific
details.
When installing new communications cards, the following guidelines
are recommended:
(1) Be sure to read the documentation for the hardware you are
installing. Pay special attention to UART base addresses and IRQ
lines, particularly if trying to set up a non-standard configuration.
(2) If you have a choice in base addresses and IRQ lines, always
choose standard values as defined above.
(3) The first port should be COM1, the second COM2, etc. Do not
skip over any port number if possible.
(4) Use SioUART to zero all unused ports (for example, call
SioUART(COM4,0) if there is no COM4 port installed).
(5) Be carefull not to configure two ports for the same address.
This is easier to do than you may believe.
(6) Choose an external modem over an internal one. It is much
easier to debug problems with an external modem than an internal one.
(7) Select hardware flow control (RTS/CTS) if flow control is
required and hardware flow control is not the default.
(8) Always test your port as soon as it is installed. Try several
programs that use the communications ports.
(9) If your serial card has two or more ports, run SELFTEST after
configuring it for your new card.
PCL4C Users Manual Page 21
6.3 Running 3 or 4 Ports Concurrently
PCL4C supports up to 4 serial ports running concurrently (more if
you have a DigiBoard or BOCA board). One free interrupt for each
port is required. Refer to the next section if you have a DigiBoard
or BOCA board.
Interrupts IRQ4 and IRQ3 are dedicated to the communications ports
in a standard IBM PC/XT/AT configuration. IRQ4 is shared between
COM1 and COM3 while IRQ3 is shared between COM2 and COM4. This means
that you can run two ports simultaneously provided that they don't
share an interrupt.
Suppose that you wish to run 3 ports simultaneously. To begin, you
must have 3 UARTs (serial ports) installed on your computer. Assume,
for purposes of this discussion, that COM1 is installed on your
motherboard, and that you have purchased a new 2 port serial
communications board.
You should be able to configure the first serial board port as COM2,
which uses IRQ3. Refer to the manual that came with your serial
board.
In order to run the third serial port concurrently with the first
two, an unused interrupt must be found. If your serial card can use
only IRQ3 and IRQ4, then there is no way to run a third line since
IRQ4 and IRQ3 are used for COM1 and COM2.
However, many serial cards can use other IRQs, typically IRQ2
through IRQ7. Many of the newer serial cards can use IRQs through
IRQ15. Since IRQ5 is normally used for a second printer port, it is
a good candidate for COM3. To use IRQ5 for the third serial port,
first set your serial card to use IRQ5 for COM3 (refer to your serial
card manual) and then add the following line to your applications
code before calling SioReset:
SioIRQ(COM3,IRQ5);
Don't forget to disable any device that might use IRQ5, such as a
second printer port or a music card. Unfortunately, there is no easy
way to determine that you have no conflicts until you actually
attempt to use the IRQ. If there are conflicts, your system will
probably hang and you will have to reboot.
To run a fourth serial port, another free IRQ must be found. On
some systems, IRQ7 can be used. To use IRQ7 for the fourth serial
port, first set your serial card to use IRQ7 for COM4 and then add:
SioIRQ(COM4,IRQ7);
Also note that conflicts are possible with port addresses. You cannot
have two cards using the same port address. This problem most often
occurs when adding a multiport board since each UART uses 8
consecutive port addresses.
Of course, you can select any IRQ and UART address that your serial
card can generate. But be carefull about IRQ and address conflicts.
PCL4C Users Manual Page 22
6.4 Using Multiport Cards
6.4.1 The DigiBoard
PCL4C supports the DigiBoard PC/4 and PC/8. In order to use the
DigiBoard, you must configure PCL4C using the SioPorts, SioUART, and
SioIRQ functions.
Your PC's ports must be partitioned into "standard" PC ports and
dumb card ports. Remember that standard PC ports cannot share IRQs
like the DigiBoard (or BOCA board) can. If you are using IRQ4 and
IRQ3 for standard PC ports COM1 and COM2, then you cannot use either
for DigiBoard ports (try IRQ5 or IRQ7).
Suppose that COM1 through COM2 are standard PC ports (using IRQ4 and
IRQ3) and you have installed a PC/8 DigiBoard that you wish to use
for COM3 through COM10 using interrupt line IRQ5. You choose to use
the recommended DigiBoard UART addresses starting at 0x100:
+-------------------------------------------------------------------+
| SioPorts(10,COM3,0x140,DIGIBOARD);/* COM3 = 1st DigiBoard port */ |
| Address = 0x100; /* 1st DigiBoard UART address */|
| for(Port=COM3;Port<=COM10;Port++) /* look at each port */ |
| {SioUART(Port,Address); /* set the UART address */ |
| Address += 8; /* compute next address */ |
| SioIRQ(Port,IRQ5); /* set the DigiBoard IRQ */ |
| } |
+-------------------------------------------------------------------+
The DigiBoard uses 0x140 for the status address for odd interrupts
and 0x141 for even interrupts.
Digiboard may be contacted at 6400 Flying Cloud Drive, Eden Prairie,
MN 55344. Telephone 612-943-9020 or FAX 612-943-5398.
6.4.2 The BOCA Board
PCL4C supports the dumb BOCA board. As with the DigiBoard, you must
configure PCL4C before using the BOCA board.
For example, to configure the BOCA BB2016 to use COM1 to COM16, with
base addresses starting at 0x100 and IRQ5:
+-------------------------------------------------------------------+
| SioPorts(16,COM1,0x107,BOCABOARD);/* COM3 = 1st BOCA board port */|
| Address = 0x100; /* 1st BOCA UART address */ |
| for(Port=COM1;Port<=COM16;Port++) /* look at each port */ |
| {SioUART(Port,Address); /* set the UART address */ |
| Address += 8; /* compute next address */ |
| SioIRQ(Port,IRQ15); /* set the BOCA IRQ */ |
| } |
+-------------------------------------------------------------------+
BOCA may be contacted at BOCA Research, Inc., 6413 Congress Avenue,
Suite 130, Boca Raton, FL 33487. Phone 407-241-8088, FAX
407-997-0918.
PCL4C Users Manual Page 23
6.5 Transmitter Interrupts
PCL4C comes assembled for all memory models with transmitter
interrupts enabled. PCL4C can also be assembled without transmitter
interrupts enabled by including "/DNO_TBE" on the MASM line.
When transmitter interrupts are NOT enabled, the following logic
occurs everytime SioPutc or SioPuts is called:
1. Wait for the UART transmit buffer to become empty. The UART
transmit buffer may not be empty if the previous transmit is not
completed (the UART breaks down the byte & sends 1 bit at a time).
2. When the UART transmit buffer is empty, the byte from the
SioPutc or SioPuts call is loaded into the UART transmit buffer and
control is returned to the caller.
Transmitter interrupts provide a way for your application program to
write to the serial port faster than the baud rate, but transmitter
interrupts do have several caveats. To begin, they are slower than
polled transmission, although not significantly. Secondly, they are
more complex and thus result in a slightly larger library.
The increased complexity of transmitter interrupts is due to the
fact that even though transmitter interrupts are enabled, a
transmitter interrupt can occur only when the UART transmitter
register transitions from not-empty to empty (a byte has just been
transmitted). To start the transmitter interrupt process, the first
byte in the PCL4C transmitter queue must be transmitted by SioPutc
(or SioPuts) rather than by the Interrupt Service Routine (ISR).
The remainder of the bytes in the PCL4C transmit queue are
transmitted by the ISR when the transmitter interrupt occurs. This
process is called "kickstarting" the transmitter interrupts.
When transmitter interrupts are enabled, the following logic occurs
everytime SioPutc or SioPuts is called:
1. The byte from SioPutc or bytes from SioPuts are put into the
PCL4C transmitter queue.
2. If there is no byte presently being transmitted, then the
transmitter interrupt process is kickstarted.
3. Each time a transmitter interrupt occurs, the ISR gains control,
removes the next byte from the PCL4C transmitter queue and puts it in
the UART transmit register.
While you can now call SioPutc and SioPuts faster than the baud
rate, bytes are still transmitted at the given baud rate. The
advantage of using transmitter interrupts is that an application
program can write a string of bytes to the serial transmit queue
without having to wait for those bytes to be transmitted before
regaining control.
When running a streaming protocol (one that doesn't wait for any
acknowledgement from the other side), be sure to check for
transmitter buffer overflow (eg, SioPutc returns -1).
PCL4C Users Manual Page 24
6.6 RS-232 Signals
RS-232 is the name of the serial data interface standard used to
connect computers to modems. Most IBM compatible computers are built
with at least one serial port and use either DB9 (9 pin) or DB25 (25
pin) connectors.
A summary of these pins and their function follows. For more
detailed information, refer to one of the many books dealing with
RS-232 interfacing.
Signal Ground Pin 7 (DB25), Pin 5 (DB9)
The SG line is used as the common signal ground, and must always be
connected.
Transmit Data Pin 2 (DB25), Pin 3 (DB9)
The TX line is used to carry data from the computer to the modem.
Receive Data Pin 3 (DB25), Pin 2 (DB9)
The RX line is used to carry data from the modem to the computer.
Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
The DTR line is used by the computer to signal the modem that it is
ready. DTR should be set high when talking to a modem.
Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
The DSR line is used by the modem to signal the computer that it is
ready.
Request to Send Pin 4 (DB25), Pin 7 (DB9)
The RTS line is used to "turn the line around" in half duplex
modems, and for hardware flow control in most modems that require
flow control.
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line is used to "turn the line around" in half duplex
modems, and for hardware flow control in most modems that require
flow control.
Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
The DCD line is used by the modem to signal the computer that a data
carrier signal is present.
Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
The RI line is asserted when a 'ring' occurs.
PCL4C Users Manual Page 25
6.7 National INS8250, INS16450, and INS16550 UARTs
The Personal Communications Library is based on the standard
National INS8250, INS16450, and INS16550 UARTs. The 8250 was the
original UART used in the IBM PC, whereas the 16450 is a faster
version found on most 286 & up machines. The 16550 contains a 16
byte FIFO to further reduce communications overhead. These UARTs
consists of 8 register ports as follows:
Offset R/W Register
0 R/W Receiver (read) / Transmitter (write)
1 R/W Interrupt Enable (read)
2 R Interrupt Identification
2 W FIFO control (INS16550 only)
3 R/W Data Format (Line Control)
4 R/W RS-232 (Modem) Control
5 R/W Line Status
6 R/W RS-232 (Modem) Status
7 R/W Not used.
For the standard PC ports (not DigiBoard or BOCA ports), the UART
registers are based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and
2E8h (COM4). COM1 and COM3 share interrupt request line IRQ4 while
COM2 and COM4 share request line IRQ3. This means that COM1 and COM3
can't be used concurrently. Similarly for COM2 and COM4.
If you have a DigiBoard (or BOCA board) installed, you will have 4
or more additional ports using INS16450 or INS16550 UARTS. The
default DigiBoard and BOCA board ports are located at 100h, 108h,
110h, etc. Refer to your DigiBoard (or BOCA board) manual.
Four sources of interrupts are possible with the 8250 and 16550: (1)
receiver error or BREAK, (2) receiver data ready, (3) ready to
transmit, and (4) RS232 input. These four sources of interrupts are
summarized as follows:
Source of Interrupt Action Required to Clear
Receiver error or BREAK. Read Line Status register.
Receiver data. Read data from data register.
Transmitter Buffer Empty. Write to data register or read IID reg.
RS232 input. Read Modem Status register.
However, PCL4C only enables transmitter and receiver interrupts.
If you are not familiar with the INS8250, several good books are
available. Refer to the Serial Communications chapter for
recommendations. Although a knowledge of the 8250 is not necessary
to use PCL4C, a general knowledge of the theory of asynchronous
serial communications is recommended.
PCL4C Users Manual Page 26
6.8 Register Summary
REG 0 : Data Register
Reading from the data register fetches the next input byte, once it
is ready. Writing to the data register transmits the byte written to
it over the serial line.
REG 1 : Interrupt Enable
The Interrupt Enable register enables each of four types of
interrupts when the appropriate bit is set to a one.
bit 3 : Enable interrupt on RS232 input.
bit 2 : Enable interrupt on receiver error or break.
bit 1 : Enable interrupt on transmitter buffer empty (TBE).
bit 0 : Enable interrupt on received data (RxRDY).
REG 2 : Interrupt Identification (IID)
Reading the Interrupt Identification (read only) register once an
interrupt has occurred identifies the interrupt as follows:
Bit 2 Bit 1 Bit 0 Priority Interrupt
0 0 1 none none
1 1 0 0 (high) Serialization or break.
1 0 0 1 Received data.
0 1 0 2 Transmitter Buffer Empty.
0 0 0 3 (low) RS232 Input.
In the INS16650, REG 2 (write only) is also the FIFO control
register. Writing bits 6 & 7 will set the FIFO trigger level
(number of bytes received before an interrupt is generated).
Bit 7 Bit 6 Trigger Bit 7 Bit 6 Trigger
0 0 1 byte 1 0 8 bytes
0 1 4 bytes 1 1 14 bytes
REG 3 : Line Control
RS232 line parameters are selected by writing to this register.
bit 7 : DLAB = 0
bit 6 : BREAK on(1), off(0).
bits 5-3 : Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
bit 2 : One stop bit(0), two stop bits(1).
bits 1-0 : Data bits = 5 (00), 6(01), 7(10), 8(11).
When the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1
become the LS and MS bytes of the Baud Rate Divisor registers.
Baud Divisor Baud Divisor Baud Divisor
300 0180 4800 0018 38400 0003
1200 0060 9600 000C 57600 0002
2400 0030 19200 0006 115200 0001
PCL4C Users Manual Page 27
REG 4 : Modem Control
RTS, DTR, loopback testing, and General Purpose Outputs #1 and #2 are
controlled by the Modem Control register as follows:
bit 4 : Enable local loopback.
bit 3 : Enable GP02. Necessary for 8250 interrupts.
bit 2 : Enable GP01.
bit 1 : Set / clear RTS.
bit 0 : Set / clear DTR.
REG 5 : Line Status
Reading the Line Status register provides status information as
follows (1 for TRUE, 0 for FALSE) :
bit 6 : Transmitter Empty.
bit 5 : Transmitter Buffer Empty (TBE).
bit 4 : BREAK detect.
bit 3 : Framing error.
bit 2 : Parity error.
bit 1 : Overrun error.
bit 0 : Data Ready.
REG 6 : Modem Status
Reading the Modem Status register provides the following status
information (1 for TRUE, 0 for FALSE) :
bit 7 : DCD status.
bit 6 : RI status.
bit 5 : DSR status.
bit 4 : CTS status.
bit 3 : Delta DCD status.
bit 2 : Delta RI status.
bit 1 : Delta DSR status.
bit 0 : Delta CTS status.
The delta bits (bits 0 through 3) are set whenever one of the status
bits (bits 4 through 7) changes (from 0 to 1 or from 1 to 0) since
the last time that the Modem Status register was read. Reading the
Modem Status register clear the delta bits.
REG 7 : Scratch Register
There is no function associated with register 7. It does not exist
in early versions of the 8250.
PCL4C Users Manual Page 28
7.0 Example Programs
Six (real mode) example programs are include with PCL4C. In
addition, the Personal Protocol Library for C (PPL4C) includes the
terminal program TERM which features ASCII, XMODEM, YMODEM, and
ZMODEM protocol transfers. Complete source code is included in the
shareware product for all of the protocols above except ZMODEM. In
order to get ZMODEM source, PPL4C must be registered.
7.1 MINIMAL
MINIMAL is the simpliest possible communications program. It
displays on the screen what it reads from the serial port and
transmits over the serial line what is typed at the keyboard. COM1
and 9600 baud are hard coded for simplicity.
7.2 SIMPLE
SIMPLE is a simple terminal program. It operates like MINIMAL,
except that both a port and a baud rate can be specified. For
example. SIMPLE32.C is the 32-bit equivalent.
SIMPLE 1 9600
7.3 LOGIN
LOGIN is programmed to dial our support BBS (205-880-9748) and log
on as GUEST. Start LOGIN like SIMPLE by providing a COM port and a
baud rate. For example,
LOGIN 1 38400
7.4 SPAWN and DOOR
The SPAWN program is the same as the SIMPLE program except that it
spawns DOOR when the user types a '$'. For example, to start SPAWN on
COM3, type
SPAWN 3
The DOOR program is also the same as SIMPLE except that it can "take
over" a serial port without changing any of the port parameter.
Exiting DOOR returns to the invoking program (SPAWN).
7.5 SELFTEST
The SELFTEST.C [or SELF32.C] program is designed to test serial
ports provided that one port (with a loopback adapter) or two ports
(connected together with a null-modem adapter) are avaiable. SELFTEST
can also be used to test your multiport board.
For example, to test PC port COM1 against COM2, type:
SELFTEST PC 1 2
SELFTEST may need to be configured for non-standard PC ports or your
multiport board. Refer to the SELFTEST source code for more info.
PCL4C Users Manual Page 29
8.0 Legal Issues
8.1 Registration
If you wish to register the PCL4C library (which also includes the
32-bit protected mode version), please send $75 plus $5 S&H ($10
outside of North America) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
The $75 price is good for one year from the date on the title page of
the manual. Call for the current price after one year.
Multiple copies are available: $55 for 3 to 9, $45 for 10 to 19, and
$35 for 20 or more. A site license is also available for $675
(includes 20 sets of printed documentation). We pay shipping.
We accept American Express, MasterCard, and VISA (account number,
expiration date, exact name on your card, and complete card billing
address required), checks in US dollars drawn on a US bank, purchase
orders (POs) from recognized US schools and companies listed in Dun &
Bradstreet, and COD (street address and phone number required) within
the USA (plus an additional $4.50 COD charge).
You can also order PCL4C from The Public Software Library (PSL) in
Houston Texas with your American Express, MasterCard, VISA, or
Discover card by calling 800-242-4PSL (from overseas: 713-524-6394)
or by FAX at 713-524-6398 or by CompuServe at [71355,470]. THESE
NUMBERS ARE FOR ORDERING ONLY. The product number for PCL4C is 10908.
Please have your credit card billing address ready.
If you wish to update from an older version of PCL4C, send $25 plus
$5 S&H ($10 outside of North America). Updates must be ordered
directly from MarshallSoft Computing.
The registered package includes:
o Small, Compact, Medium, Large, 16-bit PM & 32-bit PM libs.
o COM1 thru COM20 supported for all libs.
o Assembler source code for the library [16-bit only].
o Printed Users and Reference Manuals.
o Telephone, FAX, and BBS support for one year.
Print the file INVOICE.DOC if an invoice is needed. The registered
user will receive the latest version of PCL4C shipped by two day
priority mail (packet airmail overseas). A 3.5" diskette is provided
unless a 5.25" diskette is requested.
PCL4C Users Manual Page 30
8.2 License
MarshallSoft Computing, Inc. grants the registered user of PCL4C the
right to use one copy of the PCL4C library (in object form) on a
single computer in the development of any software product (other
than libraries such as PCL4C). The user may not use the library on
more than one computer at the same time. The source code for the
library (PCL4C.ASM) is copyrighted by MarshallSoft Computing and may
not be released in whole or in part.
Products developed using the registered version of PCL4C or PCL4C32
may include the object form of the library and may be distributed
royalty free.
Under no circumstances can PCL4C or PCL4C32 be used for any
commercial purpose without registration.
8.3 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND
SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR
ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR
DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO
EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH
DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE
SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE
SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE
SOFTWARE.
Some states do not allow the exclusion of the limit of liability for
consequential or incidental damages, so the above limitation may not
apply to you.
This agreement shall be governed by the laws of the State of Alabama
and shall inure to the benefit of Marshallsoft Computing, Inc. and
any successors, administrators, heirs and assigns. Any action or
proceeding brought by either party against the other arising out of
or related to this agreement shall be brought only in a STATE or
FEDERAL COURT of competent jurisdiction located in Madison County,
Alabama. The parties hereby consent to in personam jurisdiction of
said courts.
PCL4C Users Manual Page 31
9.0 Summary
9.1 Revision History
Version 1.0 - 14 January 1991 - original release.
Version 1.1 - 11 March 1991
o Added SioUnGetc function to library.
Version 1.2 - 1 June 1991
o SioParms bug - could not call before SioReset.
o SioReset bug - was not saving & restoring all regs.
Version 1.3 - 1 July 1991
o Added NORESET option to SioReset.
o Added SioDSR, SioCTS, SioDCD, SioLoopBack, and SioRI.
Version 2.0 - 1 Nov 1991
o Reorganized as four memory model libraries.
o Added SioModel function to library.
o Added support for Quick C and Power C.
Version 2.1 - 1 Dec 1991
o Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.
Version 3.0 - 15 Jan 1992
o Added SioUART function.
o Added "UART undefined" error code.
o Added "Bad or missing UART" error code.
o Added "Port already enabled" error code.
o Added "Cannot enable both COM1 & COM3 ..." error code.
o Fixed several minor bugs (using new automated testing).
Version 3.1 - 1 March 1992
o Added SioFIFO (INS16550 support).
o Added SioIRQ function.
o Increased maximum receive buffer size to 32K bytes.
Version 3.2 - 1 May 1992
o Modified SioReset so that it no longer clears DTR & RTS.
o Modified SioModel & renamed to SioInfo.
o Fixed bug in SioDone when using 2 ports simultaneously.
o Added SioFlow to library.
o Added YMODEM-G protocol to TERM program.
Version 3.3 - 3 August 1992
o Fixed bug in SioUnGet when using 2 ports simultaneously.
o Add SioRead function.
Version 3.4 - 4 Jan 1993
o Library modified to use up to four ports simultaneously.
o SioIRQ was modified to include a third argument.
o EXAMPORT utility distributed to registered users.
PCL4C Users Manual Page 32
9.1 Revision History (continued)
Version 3.5 - 15 May 1993
o Supports dumb DigiBoards ( PC/4 and PC/8).
o Two new error traps added ("No such IRQ" & "No such ISR").
o ASCII file transfer protocol added to TERM (with XON/XOFF).
Version 4.0 - 18 Oct 1993
o The library supports transmitter interrupts.
o Corrects bug in Ver 3.5 requiring calling SioIRQ for COM3/4.
o All example code compiles with supported C++ compilers.
o The SioIRQ function has been simplified.
Version 4.1 - 1 May 1994
o Transmitter FIFO enabled.
o Minor internal modifications.
o Supports dumb BOCA boards (BB1004, BB1008, & BB2016).
o Port definition extented to COM16.
Version 4.2 - 1 Sept 1994
o A flow control bug was fixed.
o SioGetDiv function added.
o SioRxBuf & SioTxBuf function modified.
Version 4.3 - 15 March 1995
o BREAK detection bug fixed,
o Port definitions extended to COM20.
o Support for IRQ8 through IRQ15.
o Line status bits preserved.
Version 5.0 - 20 November 1995
o Supports Protected Mode
o Renamed SioRxFlush to SioRxClear.
o Renamed SioTxFlush to SioTxClear.
o Added SioTxFlush
o Added more choices in SioInfo.
o Removed SioCrtWrite (use putch instead).
o Removed SioKeyPress (use kbhit instead).
o Removed SioKeyRead (use getch instead).
o Added SioGets & SioPuts.
Version 6.0 - 21 October 1996
o Only force 15 bytes (not 16) into TX side FIFO.
o Handles simultaneous BOCA interrupts under all conditions.
o Added 32-bit library!
PCL4C Users Manual Page 33
9.2 Function Summary
Refer to the PCL4C Reference Manual (PCL4C.REF) for detailed
information on the communications and support functions. A one line
summary of each function follows:
SioBaud Sets the baud rate of the selected port.
SioBrkKey Returns non-zero if the Control-BREAK key was pressed.
SioBrkSig Asserts, cancels, or detects BREAK signal.
SioCTS Reads the Clear to Send (CTS) modem status bit.
SioDCD Reads the Data Carrier Detect (DCD) modem status bit.
SioDelay Delays one or more tics (18 tics per second).
SioDone Terminates further serial processing.
SioDSR Reads the Data Set Ready (DSR) modem status bit.
SioDTR Set, clear, or read the Data Terminal Ready (DTR) bit.
SioError Displays error in text.
SioFIFO Sets the interrupt level for the INS16550.
SioFlow Enables / disables hardware flow control.
SioGetc Reads the next character from the serial line.
SioGets Reads a buffer of characters from the serial line.
SioGetDiv Reads the baud rate divisor registers.
SioInfo Returns library information (version number, etc.)
SioIRQ Assigns an IRQ line to a port.
SioLine Reads the line status register.
SioLoopBack Performs a UART loopback test.
SioModem Reads the modem status register.
SioParms Sets parity, stop bits, and word length.
SioPorts Sets # ports, 1st DigiBoard / BOCA port & status reg.
SioPutc Transmits a character over a serial line.
SioPuts Transmits a buffer of characters over a serial line.
SioRead Reads any of 7 UART ports.
SioReset Initialize a serial port for processing.
SioRI Reads the Ring Indicator (RI) modem status bit.
SioRTS Sets, clears, or reads the Request to Send (RTS) line.
SioRxClear Clears the receive buffer.
SioRxBuf Sets up receive buffer.
SioRxQue Returns the number of characters in the receive queue.
SioTimer Returns the number of system clock tics.
SioTxBuf Sets up transmit buffer.
SioTxClear Clears the transmit buffer.
SioTxFlush Restarts transmitter interrupts thus flushing the TX queue.
SioTxQue Returns the number of characters in the transmit queue.
SioUART Sets the UART base address.
SioUnGetc "Un-gets" (puts back) a specified character.
9.3 Further Reading
The best way to learn about serial communications is to read a good
book on the subject. Several good texts are available. Two that I
like are:
(1) C Programmers's Guide to Serial Communications by Joe Campbell
(SAMS)
(2) Mastering Serial Communications by Peter Gofton (SYBEX).
PCL4C Users Manual Page 34
10.0 Other MarshallSoft Computing Products
10.1 The Personal Protocol Library for C/C++
The Personal Protocol Library for C (PPL4C) consists of a C/C++
language library which implements XMODEM, XMODEM-CRC, XMODEM-1K,
XMODEM-G, YMODEM, YMODEM-G, and ZMODEM file transfer protocols. A
script compiler and interpreter is also included which is capable of
such tasks as automatically logging onto a BBS and downloading a file
or retrieving mail. Three example script programs are included.
The protocol library (PPL4C) requires the Personal Communications
Library for C (PCL4C).
The Personal Protocol Library for C is available for $40 plus $5 S&H
($10 S&H overseas).
10.2 The EMS Expanded Memory Library
The EMS4C library implements version 3.2 of the LIM
(Lotus-Intel-Microsoft) specification for expanded memory. It will
run with either version 3.2 or 4.0 of the LIM specification.
The EMM4C library (included with the EMS4C library) is an expanded
memory manager which allows C programmers to allocate and free EMS
(expanded) memory similiar to malloc and free in the standard C
runtime library. Both EMM4C and EMS4C require that your system be
configured with expanded (EMS) memory. But, 386 & up systems can use
extended memory as expanded memory.
The EMS Expanded Memory Library for C is available for $35 plus $5
S&H ($10 S&H overseas).
10.3 Other Products
Marshallsoft Computing, Inc. makes serial communications libraries
for Windows (C/C++, Visual Basic, and DELPHI), Visual Basic (DOS),
Power Basic (DOS), and Turbo/Borland Pascal.
PCL4C Users Manual Page 35
